Introduce KEP 5975: Declarative API Definitions by jpbetz · Pull Request #5974 · kubernetes/enhancements

jpbetz · 2026-03-23T18:14:27Z

Issue link: Declarative API Definitions #5975

k8s-ci-robot · 2026-03-23T18:57:13Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: jpbetz

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~keps/prod-readiness/OWNERS~~ [jpbetz]
~~keps/sig-api-machinery/OWNERS~~ [jpbetz]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

jpbetz · 2026-03-23T19:00:24Z

@thockin @deads2k @liggitt Looking for early feedback. If there is support I'd like to merge early and work on this in the off cycle.

jpbetz · 2026-03-23T19:05:14Z

+without knowing their concrete types. Rather than relying on reflection, we would like to
+introduce two interfaces:


I'm not fully convinced this is how I'd like to generically implement wiping. One alternative is reflection.

jpbetz · 2026-04-21T20:32:20Z

Note to self: Tests that verify DeepCopy, Conversion, and all other generators are run for each type would eliminate another aspect of manual API Review.

jpbetz · 2026-04-27T22:06:41Z

+### Code generation
+
+Rather than independently enable individual code generators with tags, code generation will
+be on-by-default for all API definitions in code where declaration files exist.
+
+`GroupVersion` will be placed in external API definition directories, For example:
+
+`staging/src/k8s.io/api/admission/v1/groupversion.yaml`:
+
+```yaml
+apiVersion: apidefinitions.k8s.io/v1alpha1
+kind: GroupVersion
+
+group: admission.k8s.io
+version: v1
+modelName: io.k8s.admission
+```
+
+This file defines all common properties of a group and it's presence indicates that
+all external code generation, such as typed clients and openapi, should be run for this
+group of resources.
+
+`GroupVersionRegistration` will be placed in internal API registration directories, For example:
+
+`pkg/apis/admission/v1/registration.yaml`:
+
+```yaml
+apiVersion: apidefinitions.k8s.io/v1alpha1
+kind: GroupVersionRegistration
+
+group: admission.k8s.io
+version: v1
+externalTypes: k8s.io/api/admission/v1
+peers:
+- k8s.io/kubernetes/pkg/apis/admission
+```


@liggitt @thockin To simplify code generator management, I'm looking a way of enabling all code-generators by-default for in-tree APIs.

Initially I just tried adding a enforcement check that complained if an API author doesn't add all the +k8s:deepcopy-gen=true type tags, but @thockin mentioned look into driving the generators of small declarations. So I'm trying it out. This section shows what it would roughly look like.

Questions:

Do we have an appetite for this sort of change? It will consume review bandwidth. The alternative would be to just merge something like Enable validation-gen and add check that all code generators always enabled kubernetes#138577.

Are we okay with something where each directory that does API definition stuff has a file? Or do we want to take this in another direction (single file for an entire API resource?!)

I'm ok with a file that describes which generator to run and how. Sounds similar to https://github.com/openshift/api/blob/master/example/.codegen.yaml in OpenShift. Some issues we've had:

opt-in or opt-out or both. As the generators grow, it is sort of like admission. We have new items that contain default-on or default-off preferences and each API can have an "explicit off" or "explicit on" preference.

Configuring at group level, across all versions made for fewer files, but more painful changes when we needed to start bringing new generators online.

This became a natural place for validation and linting exceptions too. Not sure about your plan for growth there.

@JoelSpeed migrated us to the file and has been more hands on dealing with it recently.

The idea we'd like to start with is:

Here's a file that says everything code generators need to know about the API declaring files in in this directory

When present, the generators run in a way that conforms to our API guidelines

I've got a PoC that shows this working against all in-tree APIs correctly and removes the need for a bunch of generator enablement tags in each doc.go file.

I do expect this to grow. I don't want it to accumulate validation/lint exceptions here.

For ecosystem adoption, I think it's fine to use outside of k/k. I would like it to focus on opinions we have for in-tree APIs. So if 3rd parties use it, they need to buy-in to our opinions.

jpbetz · 2026-04-30T16:17:01Z

@alvaroaleman does kubebuilder depend on any of the +k8s:deepcopy=package or other generator enablement tags in doc.go?

My intuition is that this propose would not impact kubebuilder, but want to double check.

deads2k · 2026-05-01T15:13:43Z

+
+- **Main strategy**: clears status on create (`obj.Status = TypeStatus{}`),
+  and clears status changes on update (`new.Status = old.Status`).
+- **Status substrategy**: clears spec, labels, and annotations changes


Would we phrase this to clear all new fields as they're added unless we take active effort? I'd like that so we're forced to think about it.

Yes, good point. I'll rephrase this.

deads2k · 2026-05-01T15:14:58Z

+
+This requires [Spec/Status accessor interfaces](#specstatus-accessor-interfaces).
+
+### Feature-Gate Field Dropping


This probably the most valuable part for me personally.

deads2k · 2026-05-01T15:18:22Z

+
+**Hooks:**
+
+| Hook | Purpose |


no Hook for PrepareForCreate or PrepareForUpdate?

Yes, I'll call it out.

deads2k · 2026-05-01T15:20:48Z

A few questions and comments. I like the idea.

alvaroaleman · 2026-05-01T15:51:30Z

@alvaroaleman does kubebuilder depend on any of the +k8s:deepcopy=package or other generator enablement tags in doc.go?

It depends on what you mean by "depends on", it does interpret them but that probably doesn't matter for in-tree resources as I don't think there is a good reason to use it to generate DeepCopies for in-tree resources: https://github.com/kubernetes-sigs/controller-tools/blob/e17f046d11b6e9e508d11abc37891b66831aefa4/pkg/deepcopy/gen.go#L45-L47

jpbetz · 2026-05-01T15:57:17Z

@alvaroaleman does kubebuilder depend on any of the +k8s:deepcopy=package or other generator enablement tags in doc.go?

It depends on what you mean by "depends on", it does interpret them but that probably doesn't matter for in-tree resources as I don't think there is a good reason to use it to generate DeepCopies for in-tree resources: kubernetes-sigs/controller-tools@e17f046/pkg/deepcopy/gen.go#L45-L47

👍

k8s-ci-robot requested review from apelisse and deads2k March 23, 2026 18:14

jpbetz changed the title ~~Draft KEP proposal: Declarative API definitions~~ Introduce KEP 5975: Declarative API Definitions Mar 23, 2026

initial proposal

194333b

jpbetz force-pushed the declarative-apis branch from 5e16441 to 194333b Compare March 23, 2026 18:57

jpbetz commented Mar 23, 2026

View reviewed changes

jpbetz force-pushed the declarative-apis branch from 997fd43 to e2cdb54 Compare March 23, 2026 19:15

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/XXL Denotes a PR that changes 1000+ lines, ignoring generated files. labels Mar 23, 2026

jpbetz force-pushed the declarative-apis branch 2 times, most recently from 6649b90 to 5151b1a Compare March 23, 2026 21:26

k8s-ci-robot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Mar 23, 2026

jpbetz force-pushed the declarative-apis branch 4 times, most recently from 99bd9c1 to f4fe0c7 Compare March 25, 2026 18:58

Simplify KEP

1245718

jpbetz force-pushed the declarative-apis branch from f4fe0c7 to 1245718 Compare March 25, 2026 20:00

jpbetz mentioned this pull request Apr 2, 2026

Declarative API Definitions #5975

Open

5 tasks

Add note to enforce enablement of generated support code

17108a8

jpbetz mentioned this pull request Apr 24, 2026

Enable validation-gen and add check that all code generators always enabled kubernetes/kubernetes#138577

Open

jpbetz force-pushed the declarative-apis branch from 0160c85 to 37d9d16 Compare April 27, 2026 22:01

jpbetz commented Apr 27, 2026

View reviewed changes

jpbetz force-pushed the declarative-apis branch 6 times, most recently from bebb4c8 to e955197 Compare April 28, 2026 00:47

jpbetz mentioned this pull request Apr 28, 2026

Phase 1: Switch to API declaration based code generator enablement kubernetes/kubernetes#138657

Open

Explain codegen improvements

f0ed9d8

jpbetz force-pushed the declarative-apis branch from e955197 to f0ed9d8 Compare April 30, 2026 16:39

deads2k reviewed May 1, 2026

View reviewed changes

Apply feedback

d5c098f

		without knowing their concrete types. Rather than relying on reflection, we would like to
		introduce two interfaces:


		This requires [Spec/Status accessor interfaces](#specstatus-accessor-interfaces).

		### Feature-Gate Field Dropping

Conversation

jpbetz commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Mar 23, 2026

Uh oh!

jpbetz commented Mar 23, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jpbetz commented Apr 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jpbetz commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

deads2k commented May 1, 2026

Uh oh!

alvaroaleman commented May 1, 2026

Uh oh!

jpbetz commented May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jpbetz commented Mar 23, 2026 •

edited

Loading

jpbetz commented Apr 30, 2026 •

edited

Loading